package com.yc.service;

import com.yc.controller.AuthRequest;
import com.yc.controller.AuthResponse;
import com.yc.web.bean.MyUserDTO;
import jakarta.validation.Valid;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Optional;

/**
 * 用户服务接口，定义用户模块的核心业务逻辑
 */
@Service
public interface UserService {
    /**
     * 用户注册
     *
     * @param user 用户对象，包含注册所需信息
     * @return 注册结果
     */
    MyUserDTO  register(MyUserDTO user);
    /**
     * 检查用户名是否已存在
     *
     * @param username 用户名
     * @return 是否存在的结果封装
     */
    boolean checkUsernameExists(String username);
    /**
     * 用户登录。
     * @param authRequest 登录请求（用户名和密码）
     * @return 包含 JWT Token 和用户信息的响应
     * @throws IllegalArgumentException 如果用户名或密码不正确
     */
    AuthResponse loginUser(AuthRequest authRequest);
    /**
     * 用户注销（通常是客户端删除 Token，服务端无状态）。
     * 如果需要黑名单机制，可以在此实现。
     * @param token 待注销的 token
     */
    void logout(String token);
    /**
     * 获取所有用户信息 (仅限管理员)。
     * @return 用户DTO列表
     */
    List<MyUserDTO> getAllUsers();
    /**
     * 根据ID查询用户信息（管理员可以查询所有，普通用户只能查询自己）。
     * URL: GET /users/{id}
     * 权限：拥有 'ADMIN' 角色，或者请求的用户ID与路径中的ID一致。
     */
    Optional<MyUserDTO> getUserById(Long id);

    /**
     * 更新用户信息（管理员可以更新所有，普通用户只能更新自己）。
     * URL: PUT /users/{id}
     * 权限：拥有 'ADMIN' 角色，或者请求的用户ID与路径中的ID一致。
     */
    MyUserDTO updateUser(Long id, @Valid MyUserDTO userDTO);
}
